﻿// -------------------------------------------------------------------------
//    @FileName         :    NFCacheDataSaveTrans.h
//    @Author           :    Gao.Yi
//    @Date             :    2025-08-14
//    @Email			:    445267987@qq.com
//    @Module           :    NFCacheDataSaveTrans
//    @Desc             :    缓存数据保存事务基类声明
//                           提供缓存数据保存的统一接口，支持将缓存数据持久化到存储服务器
//                           作为事务框架的基础组件，支持异步保存操作
//
// -------------------------------------------------------------------------

#pragma once

#include "NFCacheData.h"
#include "NFCacheDataWithSaveDb.h"
#include "NFComm/NFObjCommon/NFTransBase.h"
#include "NFServerTypeDefine.h"

class NFISaveDb;
/**
 * @class NFCacheDataSaveTrans
 * @brief 缓存数据保存事务基类（共享内存事务对象）
 *
 * 职责：
 * - 处理缓存数据的保存操作
 * - 管理存储服务器的交互流程
 * - 支持异步保存操作的事务管理
 * - 提供可扩展的保存结果处理机制
 *
 * 使用流程：
 * 1. 创建并初始化此事务对象
 * 2. 调用具体的保存方法发起保存请求
 * 3. 处理存储服务器返回的保存结果
 * 4. 完成事务处理
 *
 * 设计特点：
 * - 提供基础的保存事务框架
 * - 支持共享内存的冷启动和热启动
 * - 可扩展的保存操作接口
 * - 完整的错误处理和事务管理
 */
class NFCacheDataSaveTrans : public NF_OBJECT_TEMPLATE_MACRO(NFCacheDataSaveTrans, EOT_CACHE_DATA_SAVE_TRANS_OBJ, NFTransBase)
public:
    /**
     * @brief 构造函数，根据共享内存模式进行初始化
     * 
     * 根据共享内存管理器的创建模式选择初始化方式：
     * - EN_OBJ_MODE_INIT：冷启动模式，调用 CreateInit() 进行完整初始化
     * - 其他模式：热启动模式，调用 ResumeInit() 进行恢复初始化
     */
    NFCacheDataSaveTrans();

    /**
     * @brief 析构函数
     * 
     * 清理资源，由于使用共享内存管理，通常无需特殊处理
     */
    ~NFCacheDataSaveTrans() override;

    /**
     * @brief 冷启动创建初始化
     * 
     * 在共享内存冷启动场景下，对新创建的事务对象进行初始化
     * 当前实现为空，如有需要可在此添加初始化逻辑
     * 
     * @return 0 表示成功
     */
    int CreateInit();

    /**
     * @brief 热启动恢复初始化
     * 
     * 在共享内存热启动场景下，从持久化数据恢复事务状态时调用
     * 当前实现为空，如有需要可在此添加恢复逻辑
     * 
     * @return 0 表示成功
     */
    int ResumeInit();

public:
    /**
     * @brief 初始化运行期参数
     *
     * 设置事务执行所需的基本参数，通常在创建事务后立即调用
     *
     * @param serverType 目标存储服类型
     * @param roleId      目标ID（单条场景）
     * @param tableId    表ID
     * @param saveObjId
     * @param transId    上层批量事务ID
     * @return 0 表示成功
     */
    int Init(int serverType, uint64_t roleId, int tableId, int saveObjId, int transId);

public:
    /**
     * @brief 处理存储服返回消息
     *
     * 根据命令类型分发处理不同的存储服务器响应消息：
     * - NF_STORESVR_S2C_SELECT：批量查询结果
     * - NF_STORESVR_S2C_SELECTOBJ：单条查询结果
     *
     * @param pSsMsgRes 指向存储服务器返回的 Protobuf 消息对象的指针
     * @param cmd       消息命令类型
     * @param tableId   表ID
     * @param seq       消息序列号
     * @param errCode   错误码
     * @return 0 表示成功，其他值为错误码
     */
    int HandleDBMsgRes(const google::protobuf::Message* pSsMsgRes, uint32_t cmd, uint32_t tableId, uint32_t seq, int32_t errCode) override;

    /**
     * @brief 事务结束回调处理
     *
     * 当当前事务完成时，通过上层批量事务ID找到父事务并回调结果。
     * 这是事务链式调用的关键环节，确保批量操作能够正确汇总结果。
     *
     * @param iRunLogicRetCode 运行逻辑返回码
     * @return 0 表示成功，其他值为错误码
     */
    int HandleTransFinished(int iRunLogicRetCode) override;

    /**
     * @brief 保存数据到数据库
     *
     * 此方法用于将缓存数据保存到数据库中。
     * 子类应实现具体的保存逻辑。
     *
     * @param pSaveDb 指向保存数据库接口的指针
     * @param iReason 调用原因/场景标识
     * @param stPbClass Protobuf 消息对象，包含需要保存的数据
     * @return 保存结果，0 表示成功，其他值为错误码
     */
    virtual int SaveCacheDataReq(NFISaveDb* pSaveDb, int iReason, const google::protobuf::Message& stPbClass);

    /**
     * @brief 保存缓存数据到数据库
     *
     * 此方法负责将缓存数据保存到数据库中。首先设置调用原因并记录日志，
     * 然后通过消息模块发送保存请求。如果请求失败，记录错误并返回失败码。
     *
     * @param iReason 调用原因/场景标识
     * @param stData Protobuf 消息对象，包含需要保存的数据
     * @return 0 表示保存成功，非 0 表示失败
     *
     * @note 此方法不直接操作数据库，而是通过消息模块发送保存请求。
     *       确保 `stData` 包含完整且正确的保存信息。
     * @warning 调用前需确保事务对象已正确初始化，避免因未初始化导致的异常行为。
     */
    virtual int SaveCacheDataReq(int iReason, const google::protobuf::Message& stPbClass);

    /**
     * @brief 处理缓存数据保存结果
     *
     * 此方法用于处理存储服务器返回的保存结果。
     * 子类应实现具体的结果处理逻辑。
     *
     * @param pRes 指向存储服务器返回的保存结果 Protobuf 消息对象
     * @param seq 消息序列号
     * @param errCode 错误码，表示保存操作的结果
     * @return 处理结果，0 表示成功，其他值为错误码
     */
    virtual int SaveCacheDataRes(const NFrame::storesvr_modobj_res* pRes, int seq, int errCode);
protected:
    /** @brief 调用原因/场景标识 */
    int m_reason;
    /** @brief 目标对象ID */
    uint64_t m_roleId;
    /** @brief 目标存储服务器类型 */
    int m_serverType;
    /** @brief 数据表ID */
    int m_tableId;
    /** @brief 上层批量事务ID，用于回调时定位父事务 */
    int m_transId;
    /** @brief 保存对象的唯一标识ID */
    int m_saveObjId;
};
